Python Argparse Täiustatud: Alamkäskude ja Kohandatud Toiminguklasside Valdamine

Pythoni argparse moodul on võimas tööriist käsurealiideste (CLI) loomiseks. Kuigi põhikasutus on suhteliselt lihtne, pakub argparse täiustatud funktsioone, mis võimaldavad luua keerukaid ja kasutajasõbralikke CLI-sid. See blogipostitus süveneb kahte sellisesse täiustatud funktsiooni: alamkäskudesse ja kohandatud toiminguklassidesse.

Miks Täiustatud Argparse?

Lihtsate skriptide puhul, millel on ainult mõned valikud, võib piisata argparse põhilistest funktsioonidest. Kuid kui teie skriptid muutuvad keerukamaks ja funktsionaalsemaks, muutub struktureeritud ja organiseeritud CLI hädavajalikuks. Täiustatud argparse funktsioonid aitavad:

• Parandada Kasutajakogemust: Pakkuda kasutajatele selge ja intuitiivne liides.
• Suurendada Koodi Hallatavust: Korraldada oma kood loogilistesse moodulitesse, muutes selle mõistmise ja hooldamise lihtsamaks.
• Suurendada Funktsionaalsust: Toetada keerukaid töövooge ja mitmeid toiminguid ühes skriptis.
• Edendada Taaskasutust: Luua taaskasutatavaid komponente, mida saab rakendada teie rakenduse erinevatele osadele.

Alamkäsud: Keerukate CLI-de Korraldamine

Alamkäsud on viis rühmitada seotud käske ühe peamise käsu alla. See on eriti kasulik rakenduste jaoks, mis täidavad mitmesuguseid erinevaid ülesandeid. Mõelge näiteks Gitile. See kasutab alamkäske ulatuslikult: git commit, git push, git pull jne. Igal alamkäsul on oma argumentide ja valikute komplekt.

Alamkäskude Rakendamine argparse abil

Alamkäskude rakendamiseks argparse abil kasutate meetodit add_subparsers(). Siin on põhinäide:

            
import argparse

# Loo peamine parser
parser = argparse.ArgumentParser(description='Lihtne näide alamkäskudega')

# Loo alamparser
subparsers = parser.add_subparsers(dest='command', help='Saadaolevad käsud')

# Loo 'add' alamkäsk
add_parser = subparsers.add_parser('add', help='Liida kaks arvu')
add_parser.add_argument('x', type=int, help='Esimene number')
add_parser.add_argument('y', type=int, help='Teine number')

# Loo 'subtract' alamkäsk
subtract_parser = subparsers.add_parser('subtract', help='Lahuta kaks arvu')
subtract_parser.add_argument('x', type=int, help='Esimene number')
subtract_parser.add_argument('y', type=int, help='Teine number')

# Parseda argumendid
args = parser.parse_args()

# Teosta toiming vastavalt alamkäskule
if args.command == 'add':
    result = args.x + args.y
    print(f'Summa on: {result}')
elif args.command == 'subtract':
    result = args.x - args.y
    print(f'Vahe on: {result}')
else:
    parser.print_help()

            

              
                Copy
              
            
          

Selles näites:

• Loome peamise parseri, kasutades argparse.ArgumentParser().
• Lisame alamparseri, kasutades parser.add_subparsers(dest='command', help='Saadaolevad käsud'). Argument dest määrab atribuudi, mis salvestab valitud alamkäsu nime.
• Loome kaks alamkäsku, 'add' ja 'subtract', kasutades subparsers.add_parser().
• Igal alamkäsul on oma argumentide komplekt (x ja y).
• Parsime argumendid, kasutades parser.parse_args().
• Kontrollime väärtust args.command, et teha kindlaks, milline alamkäsk valiti, ja seejärel teostame vastava toimingu.

Selle skripti käivitamiseks kasutaksite käske nagu:

python your_script.py add 5 3
python your_script.py subtract 10 2

Täiustatud Alamkäsu Tehnikad

1. Funktsioonide Kasutamine Alamkäskude Haldamiseks

Organiseeritum lähenemisviis on defineerida eraldi funktsioonid iga alamkäsu haldamiseks. See parandab koodi loetavust ja hallatavust.

            
import argparse

def add(args):
    result = args.x + args.y
    print(f'Summa on: {result}')

def subtract(args):
    result = args.x - args.y
    print(f'Vahe on: {result}')

# Loo peamine parser
parser = argparse.ArgumentParser(description='Lihtne näide alamkäskudega')

# Loo alamparser
subparsers = parser.add_subparsers(dest='command', help='Saadaolevad käsud')

# Loo 'add' alamkäsk
add_parser = subparsers.add_parser('add', help='Liida kaks arvu')
add_parser.add_argument('x', type=int, help='Esimene number')
add_parser.add_argument('y', type=int, help='Teine number')
add_parser.set_defaults(func=add)

# Loo 'subtract' alamkäsk
subtract_parser = subparsers.add_parser('subtract', help='Lahuta kaks arvu')
subtract_parser.add_argument('x', type=int, help='Esimene number')
subtract_parser.add_argument('y', type=int, help='Teine number')
subtract_parser.set_defaults(func=subtract)

# Parseda argumendid
args = parser.parse_args()

# Kutsu välja alamkäskuga seotud funktsioon
if hasattr(args, 'func'):
    args.func(args)
else:
    parser.print_help()

            

              
                Copy
              
            
          

Siin kasutame set_defaults(func=...), et seostada iga alamkäskuga funktsioon. Seejärel, pärast parsimist, kutsume välja vastava funktsiooni, kui see on olemas.

2. Alamkäskude Pesastamine

Saate alamkäske pesastada, et luua veelgi keerukamaid ja hierarhilisi CLI-sid. Näiteks kaaluge CLI-d pilveressursside haldamiseks:

cloud compute instance create --name my-instance --region us-east-1
cloud storage bucket list --project my-project

Selles näites on cloud peamine käsk, compute ja storage on alamkäsud ning instance ja bucket on alam-alamkäsud.

3. Reaalmaailma Näide: Rahvusvahelistamise Tööriist

Kujutage ette tööriista tõlgete haldamiseks mitmekeelses rakenduses. Saate alamkäske kasutada erinevate toimingute korraldamiseks:

translation tool add-language --code fr_FR --name "French (France)"
translation tool extract-strings --source-dir src
translation tool translate --target-language es_ES --source-file strings.pot

See lähenemisviis võimaldab selget vastutuse eraldamist ja muudab tööriista kasutamise ja hooldamise lihtsamaks, eriti kui tegemist on paljude keelte ja tõlketöövoogudega, mida saab rakendada erinevates riikides.

Kohandatud Toiminguklassid: Argumendiparserduse Kohandamine

argparse võimaldab teil defineerida kohandatud toiminguklasse, et kohandada argumentide töötlemist. See on kasulik stsenaariumide korral, kus vaikeväärtus argumentide töötlemise käitumine ei ole piisav. Toiminguklass on klass, mis pärib klassi argparse.Action ja tühistab meetodi __call__.

Kohandatud Toiminguklassi Loomine

Siin on näide kohandatud toiminguklassist, mis teisendab argumendi suurtähtedeks:

            
import argparse

class ToUpper(argparse.Action):
    def __call__(self, parser, namespace, values, option_string=None):
        if isinstance(values, list):
            setattr(namespace, self.dest, [v.upper() for v in values])
        else:
            setattr(namespace, self.dest, values.upper())

# Loo parser
parser = argparse.ArgumentParser(description='Näide kohandatud toiminguga')

# Lisa argument kohandatud toiminguga
parser.add_argument('--name', action=ToUpper, help='Nimi, mida teisendada suurtähtedeks')
parser.add_argument('--cities', action=ToUpper, nargs='+', help='Linnade loetelu, mida teisendada suurtähtedeks')

# Parseda argumendid
args = parser.parse_args()

# Prindi tulemus
if args.name:
    print(f'Nimi: {args.name}')
if args.cities:
    print(f'Linnad: {args.cities}')

            

              
                Copy
              
            
          

Selles näites:

• Defineerime klassi ToUpper, mis pärib klassi argparse.Action.
• Meetodit __call__ kutsutakse välja, kui argument leitakse. See võtab järgmised argumendid:
  • parser: ArgumentParser objekt.
  • namespace: Nimeruumi objekt, kuhu parsitud argumendid salvestatakse.
  • values: Argumendi väärtus(ed).
  • option_string: Valikustring, mida kasutati selle toimingu käivitamiseks (nt --name).
• Meetodis __call__ teisendame väärtuse suurtähtedeks, kasutades values.upper() ja salvestame selle nimeruumi, kasutades setattr(namespace, self.dest, values.upper()).
• Lisame parserile argumendi, kasutades parser.add_argument('--name', action=ToUpper, help='Nimi, mida teisendada suurtähtedeks'). Määrame argumendi action meie kohandatud toiminguklassiks.

Selle skripti käivitamiseks kasutaksite käske nagu:

python your_script.py --name john
python your_script.py --cities london paris tokyo

Kohandatud Toiminguklasside Kasutusjuhtumid

1. Sisendi Valideerimine

Saate kasutada kohandatud toiminguklasse sisendi valideerimiseks ja vea tekitamiseks, kui sisend on vale. Näiteks võite luua toiminguklassi, mis kontrollib, kas fail on olemas või kas number on kindlas vahemikus.

            
import argparse
import os

class FileMustExist(argparse.Action):
    def __call__(self, parser, namespace, values, option_string=None):
        if not os.path.exists(values):
            raise argparse.ArgumentTypeError(f'Faili ei leitud: {values}')
        setattr(namespace, self.dest, values)

parser = argparse.ArgumentParser(description='Näide faili olemasolu valideerimisest.')
parser.add_argument('--input-file', action=FileMustExist, help='Tee sisendfailini.')

args = parser.parse_args()

print(f'Sisendfail: {args.input_file}')

            

              
                Copy
              
            
          

2. Ühikute Teisendamine

Saate kasutada kohandatud toiminguklasse ühikute teisendamiseks. Näiteks võite luua toiminguklassi, mis teisendab temperatuuri Celsiuse järgi Fahrenheitiks.

3. Keeruliste Andmestruktuuride Haldamine

Kui teil on vaja argumendid parseldada keerukateks andmestruktuurideks (nt sõnastikud, objektide loendid), saate parsimisloogika haldamiseks kasutada kohandatud toiminguklasse.

4. Näide: Ajavööndite Haldamine

Kaaluge rakendust, mis peab käsitlema kuupäevi ja kellaaegu erinevates ajavööndites. Kohandatud toiminguklassi saaks kasutada kuupäevastringi parseldamiseks ja selle teisendamiseks kindlasse ajavööndisse, kasutades teeke nagu pytz.

            
import argparse
import datetime
import pytz

class TimeZoneConverter(argparse.Action):
    def __init__(self, option_strings, dest, timezone=None, **kwargs):
        super().__init__(option_strings, dest, **kwargs)
        self.timezone = timezone

    def __call__(self, parser, namespace, values, option_string=None):
        try:
            dt = datetime.datetime.fromisoformat(values)
            if self.timezone:
                tz = pytz.timezone(self.timezone)
                dt = tz.localize(dt)
            setattr(namespace, self.dest, dt)
        except ValueError:
            raise argparse.ArgumentTypeError(f"Vigane kuupäeva/kellaaja formaat. Kasutage ISO formaati (YYYY-MM-DDTHH:MM:SS): {values}")
        except pytz.exceptions.UnknownTimeZoneError:
            raise argparse.ArgumentTypeError(f"Vigane ajavöönd: {self.timezone}")

parser = argparse.ArgumentParser(description='Näide ajavööndi teisendamisega.')
parser.add_argument('--event-time', action=TimeZoneConverter, timezone='America/Los_Angeles', help='Sündmuse aeg ISO formaadis (YYYY-MM-DDTHH:MM:SS). Teisendab America/Los_Angeles ajavööndisse.')

args = parser.parse_args(['--event-time', '2024-10-27T10:00:00'])

print(f'Sündmuse aeg (Los Angeles): {args.event_time}')

            

              
                Copy
              
            
          

See näide näitab, kuidas kohandatud toimingud saavad ajavööndite teisendamist käsitleda teegi pytz abil, demonstreerides keerukamat kasutust, mis on globaalselt oluline.

Parimad Tavad Täiustatud Argparse Kasutamiseks

• Hoidke Lihtsalt: Ärge muutke oma CLI-d liiga keeruliseks. Kasutage alamkäske ja kohandatud toiminguid ainult vajadusel.
• Esitage Selged Abiteated: Kirjutage selged ja lühikesed abiteated iga käsu ja argumendi jaoks. Kasutage argumenti help funktsioonis add_argument() ulatuslikult.
• Valideerige Sisend: Valideerige alati kasutaja sisend, et vältida vigu ja turvaauke.
• Kasutage Järjepidevaid Nimetamiskonventsioone: Järgige käskude, argumentide ja valikute puhul järjepidevaid nimetamiskonventsioone. Kaaluge kebab-case (--my-option) kasutamist pikkade valikunimede puhul.
• Testige Põhjalikult: Testige oma CLI-d põhjalikult erinevate sisendite ja stsenaariumide korral.
• Dokumenteerige Oma CLI: Esitage oma CLI jaoks põhjalik dokumentatsioon, sealhulgas näited iga käsu ja argumendi kasutamise kohta. Tööriistad nagu Sphinx saavad genereerida dokumentatsiooni teie koodist.
• Kaaluge Lokaliseerimist: Kui teie CLI on mõeldud globaalsele vaatajaskonnale, kaaluge oma abiteadete ja muu kasutajale suunatud teksti lokaliseerimist.

Järeldus

Alamkäsud ja kohandatud toiminguklassid on võimsad tööriistad keerukate ja kasutajasõbralike CLI-de loomiseks argparse abil. Neid täiustatud funktsioone valdades saate luua tugevaid, hooldatavaid ja skaleeritavaid käsurearakendusi, mis vastavad mitmekesise kasutajaskonna vajadustele. Alates mitmekeelsete rakenduste haldamisest kuni ajavööndite haldamiseni üle kogu maailma on võimalused tohutud. Võtke need tehnikad omaks, et tõsta oma Pythoni skriptimise ja käsureatööriistade arendus järgmisele tasemele.